Loadstar 128 #27

home *** CD-ROM | disk | FTP | other *** search

/ Loadstar 128 #27 / q27.d81 / t.dt128 docs 9 < prev next >

Wrap

Text File | 1991-01-01 | 14.9 KB | 432 lines

Script Compiler --------------- A script is a program which you create and run within the DT128 environment. The program is created using DT128's very own script language. The language adds a powerful set of instructions which can be used to perform various useful tasks which enables you customize the operations of your terminal. Each script consists of 2 parts: source code and executable code. The source code is the actual program you create within the main buffer editor. It is the series of script language instructions you need to perform a task. This program must then be compiled using the "Script Compiler" module. The compiler translates the source code in the buffer to executable code. It is the executable code that actually runs within DT128 using the "Execute Script" module. If there is a syntax error within your source code the compiler will report the error type as well as a memory location value. This value is the offset into the buffer where the error occurred (in the editor you can press Keypad-6 and enter the value to move to that location quickly). Fix the error and re-compile. When the source code is free of syntax errors the executable code is created. You then have the option to save the code to disk. You may enter a file name of up to 12 characters. The file extension ".exe" is automatically appended to the name you provide. While it is the EXEcutable file that you run you should also save your source code to a disk file. That way if you need to make changes to your script program you can re-load your source code, modify it, re-save it, then compile the new code to create a new executable file. How to Create a Script: The first step is to load the "Script Compiler" module. You edit your script programs using the main buffer editor. There are many instructions you may use, each of which is listed below as well as an explanation of what each does. General Source Code Syntax: 1. All script language instructions must be fully capitalized. 2. A "label" is similar to BASIC's "variable" in that the usage is similar. There are 3 types of labels: A. Numeric (created with the NUMBER instruction, similar to an integer variable in BASIC) B. string (created with the STRING instruction, similar to a string variable in BASIC) C. address (these labels are defined by you and they give names to portions of your program, similar to BASIC line numbers) 3. Labels must be entirely lower case (the underscore "{CBM-@}" and digits 0- 9 are valid as long as they are not the 1st character in the label. Valid: file{CBM-@}name counter1 Invalid: {CBM-@}counter 1counter 4. Labels can be up to 32 characters in length. 5. A semi colon can be used to insert comments in your source code. ; comments follow up to next return 6. Strings can be delimited with either a quote or apostrophe. If you use a quote at the front of a string you must end the string with a quote, if you use an apostrophe to start a string you must end the string with an apostrophe. Valid: "string" or 'string' Invalid "string' 7. Spacing is not important (you can indent or space commands and labels in any format that you like to create more legible code) 8. All strings are interpreted literally. This can cause certain problems. For example, the editor uses standard ASCII codes. File names, however, should be PetAscii. Upper case ASCII characters correspond to lower case PetAscii characters. Because no string conversions are performed you will usually want to use upper case letters in file names, as well as any string that you DISPLAY or TRANSMIT to a C/G screen. An easy way to get it correct is any time you enter a file name or any string that is to be used in a PetAscii environment you turn on PetAscii input mode while entering the string. Refer to Command Set further in the document for a listing of instructions. Execute Script -------------- After you have successfully compiled a script you can run it using this module. Select the "Load Script" option and enter a 12 character file name (the file extension ".exe" is automatically appended to the name). If the file is a valid script file you can then run it in 2 different ways: 1. Select the "Execute Script" option within the module. 2. Press Alt-V in terminal mode. Scripts can be aborted by pressing the RUN/STOP key. When a script ends or is aborted you are returned to this module. When you press ESCape to exit the module you return to terminal mode if you ran the script using Alt-V from terminal mode or to the previous menu if you ran it from within the module. There are several possible messages you will see when a script ends: Stopped - the script ended or you pressed RUN/STOP. Buffer Overflow - you attempted to load a file but the buffer was filled before the entire file could be loaded. Stack Overflow - You nested too many subroutines (a subroutine called a subroutine which called a subroutine...) or a RETURN was attempted without a PERFORM previous. You can execute a script upon BOOTUP by naming the script executable file "AUTOEXEC". Executable scripts are version dependent. You will need to re-compile all source code files with each update. The Command Set: NUMBER Allows you to define a numeric variable. In the script language all defined numeric variables are 16 bit integers which means that a variable can have a whole number value from 0 - 65,535. Syntax: NUMBER label x where "label" is the variable name and "x" is its initial value (0-65535). The initial value is valid only the first time you run the script after it is loaded. If you re-execute a script the numeric value starts at whatever value it had when the script was stopped. Any instruction that requires 1 or more numeric parameters can use a numeric label except where noted. STRING Allows you to define a string variable. In the script language all strings must be 1-255 characters is length and may contain any characters. Syntax: STRING label "string" STRING label 'string' where "label" is the name of the string variable. The string can be comprised of any character as long as it has the same delimiter, the quote or apostrophe, starting and ending it. If you place a return (Ascii 13) inside the string the listing will look a bit odd but it is perfectly acceptable. Any instruction that requires 1 or more string parameters may use a string label except where noted. *** For program clarity it is recommended that you define all numeric and string variables at the start of your source code. DISPLAY Allows you to print a string or number to your screen (similar to BASIC's "PRINT" statement). Syntax: DISPLAY string{CBM-@}label DISPLAY numeric{CBM-@}label DISPLAY "literal string" DISPLAY 'literal string' You may display literal strings, string labels, and numeric labels. You cannot display literal values (DISPLAY 123 is invalid) TRANSMIT Functionally indentical to the DISPLAY instruction except that output is directed to the modem. Syntax: TRANSMIT string{CBM-@}label TRANSMIT numeric{CBM-@}label TRANSMIT "literal string" TRANSMIT 'literal string' You may transmit literal strings, string labels, and numeric labels. You cannot transmit literal values (DISPLAY 123 is invalid) TERMINAL Enters terminal mode and lights up the "S" script executing LED immediately to the right of the bytes free display. Syntax: TERMINAL EDIT Enters the buffer editor. You may then freely edit the buffer. When you exit the editor control returns to the script. Syntax: EDIT This can be useful should you need to have checkpoints in a script where you check the buffer. It can also be used on BOOTUP by first loading a file with the BLOAD instruction followed by the EDIT instruction. This enables you to provide some documentation or automatically load a regularly used file. DEVICE Allows you to change the default system device. Syntax: DEVICE x y where x is the device number 8-11 and y is the drive number 0-1 Both values must be stated explicitly. Example: DEVICE 9 0 Sets the default device to 9, drive to 0. OPENTEXT Opens the buffer to text mode. Syntax: OPENTEXT OPENALL Opens the buffer to all characters received. Syntax: OPENALL CLOSE Closes the capture buffer. Syntax: CLOSE CLEAR Clears the capture buffer. Syntax: CLEAR BLOAD Loads the buffer with the specified file name. All buffer loads are done using "True Ascii." Syntax: BLOAD "FILE NAME" BLOAD 'FILE NAME' BLOAD file{CBM-@}name{CBM-@}string Note the capitalized letters in the file name. Remember, upper case ASCII letters correspond to lower case PetAscii characters. All standard file name rules apply. BAPPEND Appends a file to the buffer. Syntax is the same as in BLOAD. BSAVE Saves the buffer to the specified file name. All buffer saves are done using "True Ascii." Syntax: BSAVE "FILE NAME" BSAVE 'FILE NAME' BSAVE file{CBM-@}name{CBM-@}string Note the capitalized letters in the file name. Remember, upper case ASCII letters correspond to lower case PetAscii characters. All standard file name rules apply. You may wish to set the file type before using this instruction (See FILETYPE). FILETYPE Allows you to define the file type for buffer saves. Syntax: FILETYPE P FILETYPE S where "P" is for PRoGram and "S" is for SEQuential. The "P" or "S" must also be capitalized and stated explicitly. SENDBUF Sends the buffer contents to the modem. Syntax: SENDBUF The buffer is transmitted as though it was one long string. This means that the current character delay (see CDELAY) and line delay (see LDELAY) settings are used. Because the RUN/STOP key is used to abort the script this function uses the COMMODORE Key to stop the send. You may also pause the transmission of characters by holding down the SHIFT key (the reception buffer is not emptied during that pause so do it with caution). You can also stop the transmission by pressing the CONTROL key. When you do this all characters that have already been sent are deleted from the buffer. This allows you to stop the transmission and restart it later with another SENDBUF command at the point you stopped it. The CONTROL function only works after a carriage return has been sent so you may have to hold the key for a brief period of time before it works. FILLBUF This instruction offers a method for automatic buffering and saving. Syntax: FILLBUF "FILE NAME" x "pause" "resume" "until" branch "FILE NAME" is the file name used to save the buffer "x" is a literal value (you cannot use a numeric label, the value must be stated explicitly) 1 - 63999. If the bytes used exceeds this value the automatic save begins. Because the C128 cannot access the disk drive and continue receiving characters from the modem it is necessary to instruct the other system to pause while the buffer is being saved otherwise you would miss characters the host was transmitted during the save. At the moment the bytes used count exceeds the "x" value the "pause" string is sent to the modem. DT128 then waits 1.5 seconds to allow the host system to recognize the pause string you sent. Most systems recognize a CTRL-S as a signal to halt transmission but some systems use a different character. Next the buffer is saved to the specified file name. If the save was completed successfully the buffer is cleared and then the "resume" string is sent to the modem to signal the host system to begin transmitting. Most systems recognize a CTRL-Q as a signal to begin transmitting after a pause but some systems use a different character. After the resume transmission string is sent the FILLBUF instruction ends and the script continues with the next instruction. It is your responsibility to make sure the buffer is opened to the capture method of choice (text or all) before you execute a FILLBUF command as well as CLEARing the buffer if need be before you start. The last two parameters provide a way to break out of the FILLBUF instruction. If the "until" string is received during execution of this instruction the FILLBUF is aborted and script execution resumes at the instruction following the address label you provided ("branch" in the example above). Example Program: STRING file{CBM-@}name "NET MAIL"; Define the string variable file{CBM-@}name FILETYPE S; Set default file type to seq CLEAR; Clear buffer TRANSMIT "Y"; we activate the script when we are at ; the prompt to begin reading messages. ; Send a "y" for "yes" to begin OPENTEXT; open the buffer to text mode ; FILLBUF file{CBM-@}name 60000 "^s" "^q" "Press any key" done ; We receive a stream of characters until the buffer has used more than 60000 bytes. If this occurs send a CTRL-S to signal the host to pause and then save the buffer. If successful clear the buffer and send a CTRL-Q to signal the host to resume. The FILLBUF then ends. If the amount of data is likely to exceed 1 buffer save you can use several FILLBUF's in a row (use a different file name). FILLBUF "NET MAIL 2" "^s" "^q" "Press any key" done ; Pretend there is more code here ; END; end the script ; done HANGUP ; If we received "Press any key" during END the FILLBUF's above execution resumes here. Hang up and end the script. In the above example we used a CTRL-S and a CTRL-Q and represented them with "^s" and "^q". In your actual program you would enter the CTRL-S and CTRL-Q directly. The caret was used here in case you decide to send this file to your printer which won't like the control characters. END Ends the execution of the script. Syntax: END NOCARRIER Most script instructions require that a carrier be present. By using NOCARRIER you can ignore the normal carrier. This can be useful if you want to send strings to the modem while you are offline. Syntax: NOCARRIER Example: (assume we are offline and our purpose is to send a command to the modem) NOCARRIER TRANSMIT "any modem command string" WAIT "OK" 5 CARRIER; restore normal carrier status CARRIER Restores the normal carrier status. A carrier must be present for each of the following commands to function properly: TRANSMIT INTEGER WAIT PROMPT SELECT/CASE/UNTIL CLOCKON Turns on the clock. Syntax: CLOCKON CLOCKOFF Turns off the clock. Useful if you want to clear the screen if you want custom displays or menus. Syntax: CLOCKOFF EXIT Exits terminal mode. Syntax: EXIT (The rest of the script commands are in Part 10.)